Add image optimization with Cloudflare Images #999

pilcrowonpaper · 2025-11-20T06:58:38Z

No description provided.

changeset-bot · 2025-11-20T06:58:42Z

⚠️ No Changeset found

Latest commit: 4e4a7f9

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pilcrowonpaper · 2025-11-20T06:59:58Z

packages/cloudflare/src/cli/templates/images.ts

+					status: 508,
+				});
+			}
+			throw new Error("Failed to fetch image");


This is consistent with Next.js but not sure if a 500 response is the best if the URL is invalid

sommeeeer · 2025-11-20T07:08:46Z

Hello @pilcrowonpaper, good to see you here :) looks good on first glance, I'll do another review later!

pkg-pr-new · 2025-11-20T07:11:28Z

Open in StackBlitz

npm i https://pkg.pr.new/@opennextjs/cloudflare@999

commit: 4e4a7f9

pilcrowonpaper · 2025-11-20T08:01:03Z

packages/cloudflare/src/cli/templates/images.ts

+	} else {
+		const cacheControlHeader = imageResponse.headers.get("Cache-Control");
+		if (cacheControlHeader !== null) {
+			immutable = cacheControlHeader.includes("immutable");


Next.js does something more complicated and bases the optimized response on the upstream Cache-Control header. I didn't want to do anything complex for now so it just checks if the upstream image is a static content

pilcrowonpaper · 2025-11-21T01:14:32Z

It looks like the Playwright tests are failing because the test cases don't include the required w and q parameters.

pilcrowonpaper · 2025-11-21T01:20:46Z

packages/cloudflare/src/cli/build/open-next/compile-images.ts

 	const __IMAGES_CONTENT_DISPOSITION__ = JSON.stringify(
 		imagesManifest?.images?.contentDispositionType ?? "attachment"
 	);
+	const __IMAGES_MAX_REDIRECTS__ = JSON.stringify(imagesManifest?.images?.maximumRedirects ?? 3);


This was changed to 3 from unlimited in Next.js 16

We could use unlimited then (and maybe add your comment as a code comment on this file/line)

pilcrowonpaper · 2025-11-21T01:21:37Z

packages/cloudflare/src/cli/build/open-next/compile-images.ts

+
+const defaultDeviceSizes = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const defaultImageSizes = [32, 48, 64, 96, 128, 256, 384];
+const defaultQualities = [75];


Before Next.js 16, the default behavior was to allow values from 1-100

pilcrowonpaper · 2025-11-21T01:22:03Z

packages/cloudflare/src/cli/build/open-next/compile-images.ts

 }
+
+const defaultDeviceSizes = [640, 750, 828, 1080, 1200, 1920, 2048, 3840];
+const defaultImageSizes = [32, 48, 64, 96, 128, 256, 384];


Before Next.js 16, 16 was also included

I would use Next 16 (and add comments on the lines).

nit: maybe move those constants up (i.e. before they are used)

pilcrowonpaper · 2025-11-21T01:27:13Z

packages/cloudflare/src/cli/templates/images.ts

+async function fetchImage(url: string, count: number): Promise<FetchImageResult> {
+	let response: Response;
+	try {
+		response = await fetch(url, {


I haven't added support for dangerouslyAllowLocalIP, which checks if a domain resolves to a private IP.

vicb · 2025-11-21T10:36:52Z

packages/cloudflare/src/cli/templates/worker.ts

 			) {
-				const imageUrl = url.searchParams.get("url") ?? "";
-				return await fetchImage(env.ASSETS, imageUrl, ctx);
+				return await handleImageRequest(url, request.headers, env);


nit: maybe pass the request instead of url and headers to handleImageRequest ?

We already create a URL instance in the worker so this allows us to reuse it and avoid parsing the URL string twice

pilcrowonpaper · 2025-11-21T10:37:29Z

@vicb
Should the behavior match Next.js 15 or 16 in general? Or should we check the version and change the behavior based on it? Not sure what the policy is on Next.js versions

vicb · 2025-11-21T10:37:38Z

packages/cloudflare/src/cli/templates/images.ts

 };

-let NEXT_IMAGE_REGEXP: RegExp;
+export async function handleImageRequest(


Could you please add JSDoc to this function

vicb · 2025-11-21T10:39:30Z

packages/cloudflare/src/cli/templates/images.ts

+		const result: ErrorResult = {
+			ok: false,
+			message: '"url" parameter is required',
+		};
+		return result;


nit: That should be enough?

Suggested change

const result: ErrorResult = {

ok: false,

message: '"url" parameter is required',

};

return result;

return {

ok: false,

message: '"url" parameter is required',

};

Personally I don't like returning objects directly and prefer explicitly defining the type. I can change it if it bothers you

you can use satisfies if you really want to add a type.
But all "nit" comments are mostly suggestion, pick what you prefer.

vicb · 2025-11-21T10:42:31Z

packages/cloudflare/src/cli/templates/images.ts

+		url = urlQueryValue;
+
+		const pathname = getPathnameFromRelativeURL(url);
+		if (/\/_next\/image($|\/)/.test(decodeURIComponent(pathname))) {


What about /_next/image?url

Sorry, I don't understand?

It would not match as you have a $

It matches against the pathname so it should be fine, no? It matches against /_next/image, /_next/image/, and /_next/image/*

vicb · 2025-11-21T10:43:40Z

packages/cloudflare/src/cli/build/open-next/compile-images.ts

 		: {};

 	const __IMAGES_REMOTE_PATTERNS__ = JSON.stringify(imagesManifest?.images?.remotePatterns ?? []);
+	const __IMAGES_LOCAL_PATTERNS_DEFINED__ = JSON.stringify(


Is this needed given that __IMAGES_LOCAL_PATTERNS__ default to an empty list?

Yes, Next.js treats undefined and an empty list differently

vicb · 2025-11-21T10:50:12Z

packages/cloudflare/src/cli/templates/images.ts

+		return result;
+	}
+	const widthQueryValue = widthQueryValues[0]!;
+	if (!/^[0-9]+$/.test(widthQueryValue)) {


nit

Suggested change

if (!/^[0-9]+$/.test(widthQueryValue)) {

if (!/^\d+$/.test(widthQueryValue)) {

For context, most of the parameter validation is based on Next.js' own code

vicb · 2025-11-21T10:51:23Z

packages/cloudflare/src/cli/templates/images.ts

+		if (!hasRemoteMatch(remotePatterns, parsedURL)) {
+			const result: ErrorResult = {
+				ok: false,
+				message: '"url" parameter is not allowed',


maybe you can drop ok and rename "message" to "error"?

I personally don't like dealing with undefined and optional parameters so I prefer having with an ok property that is always defined, but let me know if you want me to change it

vicb · 2025-11-21T10:52:21Z

packages/cloudflare/src/cli/templates/images.ts

+		url: url,
+		width: width,
+		quality: quality,
+		format: format,
+		static: staticAsset,


nit:

Suggested change

url: url,

width: width,

quality: quality,

format: format,

static: staticAsset,

url,

width,

quality,

format,

static: staticAsset,

vicb · 2025-11-21T10:52:50Z

packages/cloudflare/src/cli/templates/images.ts

-		return new Response('"url" parameter is valid but upstream response is invalid', {
-			status: 400,
-		});
+type ParseImageRequestURLResult = ParseImageRequestURLSuccessResult | ErrorResult;


nit: move the type above the function where they are used

vicb · 2025-11-21T10:54:42Z

packages/cloudflare/src/cli/templates/images.ts

 const WEBP = "image/webp";
 const PNG = "image/png";
 const JPEG = "image/jpeg";
-const JXL = "image/jxl";


Question: why have those been removed? (IIRC it comes from Next)

I've removed formats that aren't supported by Cloudflare:
https://developers.cloudflare.com/images/transform-images/

What happens if the image binding is not used and we try to access one of this removed type?

That part I was unsure. I personally think we should only serve images that are supported by the optimization process, even when the binding isn't defined. It'd be weird if your images stopped being served when you turn on image optimization by defining the binding. It will be a breaking change though

vicb · 2025-11-21T10:57:01Z

packages/cloudflare/src/cli/templates/images.ts

+	let imageResponse: Response;
+	if (parseResult.url.startsWith("/")) {
+		if (env.ASSETS === undefined) {
+			console.error("env.ASSETS binding is not defined.");


use the logger rather than console.

Also we should fallback to the former behavior (serve unoptimized images) when the binding is not present)

Oops that's ASSET, nvm the comment about former behavior but still please switch to using the logger.

I've had some issues with wrangler not being able resolve @opennextjs/aws imports but I'll look into it again

vicb · 2025-11-21T11:01:03Z

packages/cloudflare/src/cli/templates/images.ts

+		const imageTransformationResult = await imageSource
+			.transform({
+				width: parseResult.width,
+				fit: "scale-down",


question: Does ~~not~~ Next always use scale-down?

Unsure. There's so no documentation on the default value
https://developers.cloudflare.com/images/transform-images/transform-via-url/#fit

Sorry for the typo in my initial message, the question was about Next

I'll need to double check, but I just assumed so because you mentioned that the images shouldn't be scaled more than the original size. (For context, scale-down will only scale down and never scale up images.)

vicb

Awesome @pilcrowonpaper !

I have done a frist round of review.

Could you please add JSDoc comments to added functions.
Maybe there could be separate functions to i.e. validate each parameter?

Hinata Masaki added 2 commits November 20, 2025 15:56

initial commit

ab5bec8

update examples

4e4a7f9

pilcrowonpaper commented Nov 20, 2025

View reviewed changes

pilcrowonpaper commented Nov 21, 2025

View reviewed changes

vicb reviewed Nov 21, 2025

View reviewed changes

	if (!/^[0-9]+$/.test(widthQueryValue)) {
	if (!/^\d+$/.test(widthQueryValue)) {

Add image optimization with Cloudflare Images #999

Are you sure you want to change the base?

Add image optimization with Cloudflare Images #999

Conversation

pilcrowonpaper commented Nov 20, 2025

Uh oh!

changeset-bot bot commented Nov 20, 2025

⚠️ No Changeset found

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sommeeeer commented Nov 20, 2025

Uh oh!

pkg-pr-new bot commented Nov 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pilcrowonpaper commented Nov 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pilcrowonpaper commented Nov 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

vicb Nov 21, 2025 •

edited

Loading